home *** CD-ROM | disk | FTP | other *** search
/ Night Owl 6 / Night Owl's Shareware - PDSI-006 - Night Owl Corp (1990).iso / 037a / boi120.zip / BOI120.DOC next >
Text File  |  1990-12-12  |  20KB  |  479 lines
  1. BOI Reference Manual 1.20  12/15/90
  2.  
  3.  
  4.     BBS Onliner Interface 1.20
  5.     (C) 1990 Andrew J. Mead
  6.     All Rights Reserved.
  7.  
  8.     Contact:
  9.     POB 1155
  10.     Chapel Hill, NC 27514-1155
  11.           or
  12.     1:151/223.36 FidoNet
  13.     #98@9968 WWIVnet
  14.  
  15.     Turbo Pascal and TP are registered trademarks of Borland International.
  16.     Quick Basic and QB are registered trademarks MicroSoft Incorporated.
  17.  
  18.  
  19.     Sections in order of Appearance
  20.       Initial Statement
  21.       ShareWare Liscense Agreement
  22.       Registration Cost
  23.       Technical Support
  24.       Registration Agreement
  25.       UNIT BIODECL
  26.       UNIT GETCMBBS
  27.       UNIT IOLIB
  28.       UNIT ASYNC
  29.       UNIT IOSUPP
  30.       UNIT SUPPORT
  31.       BOI Documentation Files
  32.       Future Enhancements
  33.       Implementation Discussion
  34.  
  35.  
  36.     Initial Statement
  37.       I would like to see the command line switches used by this interface
  38.       become a standard for BBS online doors.  Since the BBS programmers
  39.       are not creating a standard drop file very quickly, we door programmers
  40.       will need to make do.  If you are not a Turbo Pascal programmer, I
  41.       still ask that you consider implementing my command line switching
  42.       system.
  43.  
  44.       The UNIT sections of this document detail the functionality of each
  45.       procedure and function contained in each unit.  Unit BIODECL is
  46.       pretty much self explanatory, and looking at it directly is the
  47.       best way to get information on it.
  48.  
  49.  
  50.     ShareWare Liscence Agreement
  51.       This package is ShareWare.  If you use this package, please send me
  52.       money.  Feel free to use the ideas and code from this package, but
  53.       if you use the interface itself to any extent, place the following
  54.       on the opening or copyright screen.
  55.  
  56.       BBS Onliner Interface version 1.20
  57.       (C) 1990 Andrew J. Mead
  58.       All Rights Reserved.
  59.       Contact: POB 1155 Chapel Hill, NC 27514-1155
  60.  
  61.       If you alter the code, put your revision number AFTER the '1.20'
  62.       ie (version 1.20 revision 1.0).  I will maintain, and steadily
  63.       update the interface.  If you have any ideas, suggestions, or
  64.       improvements, please send them to me.  There is plenty of room for
  65.       improvement in the interface.
  66.  
  67.  
  68.     Registration Costs
  69.       If you use the interface, I ask that you pay a royalty of $1U.S.
  70.       per registration.  If the door you release has a registration fee
  71.       of less than $10, I waive this request.  The money recieved from
  72.       the BOI will be set aside to pay for distribution of later versions
  73.       and my phone bill.  If you register, I will make every effort to
  74.       make sure that you recieve every upgrade.  The registration fee
  75.       for the BOI is $35.00 U.S. (and is credited against any future
  76.       royalties).  There will be a Turbo C version of the interface
  77.       available in 1991.  See BOIREG.DOC for registration form.
  78.  
  79.  
  80.     Technical Support
  81.       I am always willing to offer support.  I can be reached at #98@9968
  82.       on the WWIVnet and 1:151/223.36 on the FidoNet.  A support conference
  83.       on both systems may become available if demanded.  Please be specific
  84.       with your questions, and include any details you have.  If someone
  85.       out there would like to help with the technical support, let me know.
  86.  
  87.  
  88.     UNIT BIODECL
  89.       See BIODECL.PAS for documentation.  This Unit is merely a
  90.       clearing house for public variables and constants.  This is used
  91.       by every other unit and the door program itself.
  92.  
  93.     UNIT GETCMBBS
  94.  
  95.       Uses
  96.         Dos
  97.         BOIDecl
  98.  
  99.       Procedure
  100.         GetCommand
  101.  
  102.       Procedure GETCOMMAND(infofile, inhof, logfile : pathstr;
  103.           gamename, version : string;  programset : charset);
  104.  
  105.         infofile   - name of the doors documentation file.
  106.         inhof      - default name for text hall of fame (can be '').
  107.         logfile    - name of error log.
  108.         gamename   - name of the door.
  109.         version    - door version number (string).
  110.         programset - set of door defined command line arguments.  Must
  111.             be in ['+','-','=','[',']','.'].  These arguments are to
  112.             be processed by the door itself.
  113.  
  114.         GetCommand is the front-end of the interface.  it reads the
  115.         BBS dropfile, and initializes the communications settings.
  116.  
  117.  
  118.     UNIT IOLIB
  119.  
  120.       Uses
  121.         Dos
  122.  
  123.       Functions
  124.         Exist                     GetTimer                  IntStr
  125.         KeyPressed                LeftTime                  Max
  126.         Min                       PadStr                    PortKeyPressed
  127.         ReadKey                   ReadPortKey               RealStr
  128.         Valid                     WhereX                    WhereY
  129.  
  130.       Procedures
  131.         ClearBuffers              ClrPortEol                ClrPortScr
  132.         Delay                     DoTimeOut                 EndPort
  133.         GetString                 GotoPortXY                PortBackground
  134.         PortColor                 PortColumnOne             PortWindow
  135.         ResetPortXY               SendString                SetPort
  136.         SetPortXY                 TextPortColor             TimerSet
  137.  
  138.       Procedure CLEARBUFFERS
  139.         ClearBuffers empties both the host keyboard and the port input
  140.         buffers.  This procedure is helpful in controlling 'Type-ahead'
  141.         problems.  With a 1k port input buffer, the remote user could
  142.         inadvertently lean a key putting hundreds of key-strokes into the
  143.         buffer.
  144.  
  145.       Procedure CLRPORTSCR                                  ANSI
  146.         ClearPortScr sends the ANSI code to clear the defined screen
  147.         window (PortWindow).  If there is a remote user, the current
  148.         status line will be written on line 25 on the host screen.
  149.         This replaces TPs CRT ClrScr.
  150.  
  151.       Procedure CLRPORTEOL                                  ANSI
  152.         ClearPortEol sends the ANSI code to clear the current line from
  153.         the current cursor position to the right edge of the screen.
  154.  
  155.       Procedure DELAY(ms : Word)                            BIOS
  156.         This procedure is identical to the one in TPs CRT Unit.  ms
  157.         is the approxiamate time of CPU delay in milliseconds (993 per
  158.         second).
  159.  
  160.       Procedure DOTIMEOUT(ringbell : boolean)
  161.         This procedure is called upon modem or user inactivity time-out.
  162.         There should be no reason for the door itself to call this procedure.
  163.         ringbell tells it to echo a bell to the remote user (if communications
  164.         still exist).
  165.  
  166.       Procedure ENDPORT
  167.         EndPort should be the last line of your door program.  This procedure
  168.         disables the BIO Async routines, and restores the previously
  169.         installed routines.  This procedure should be called before
  170.         the program ends, especially during abnormal termination, so that
  171.         the BBSs communication routines are re-established.  See SetPort.
  172.  
  173.       Function EXIST(thisfile : pathstr) : boolean
  174.         Exists tells whether or not ThisFile exists or not.  Should be used
  175.         in conjunction with Valid.  This is a public domain function.
  176.  
  177.       Procedure GETSTRING(var gstr : string)
  178.         GetString returns all characters input locally and from remote upto
  179.         the next carriage return.  This is a 'dumb' procedure, and will not
  180.         reject any characters.  See ReadKey and ReadPortKey.
  181.  
  182.       Function GETTIMER(var basetime : longint; val : word) : boolean
  183.         basetime - clockticks since midnight (18.2 per second)
  184.         val      - number of seconds
  185.  
  186.         GetTimer returns true if val seconds have passed since basetime.
  187.         You must use SetTimer to initialize basetime.  These two procedures
  188.         can be used for many purposes including benchmarks and user
  189.         inactivity timeouts.  See SetTimer.
  190.  
  191.       Procedure GOTOPORTXY(x,y : byte)                      ANSI
  192.         GotoPortXY uses ANSI codes to position the cursor.  Replaces
  193.         TPs CRT GotoXY.
  194.  
  195.       Function INTSTR(val : longint; isize : byte) : string
  196.         val   - ennumerated value to convert to a string
  197.         isize - size of string
  198.  
  199.         IntStr returns a string of an integer value.  Best utilized by
  200.         SendString for formatted (left or right justified) output.
  201.         See SendString, PadStr, RealStr.
  202.  
  203.       Function KEYPRESSED : Boolean
  204.         KeyPressed replaces TPs CRT KeyPressed.  It returns true if
  205.         there is a key waiting in the local keyboard buffer.  You should
  206.         use PortKeyPressed for general use.
  207.  
  208.       Function LEFTTIME : integer
  209.         LeftTime returns the users current time remaining in minutes.
  210.  
  211.       Function MAX (a,b : word) : word
  212.         Max returns the greater of a and b.
  213.  
  214.       Function MIN (a,b : word) : word
  215.         Min returns the lesser of a and b.
  216.  
  217.       Function PADSTR(pstr : string; psize : byte) : string
  218.         pstr  - input string
  219.         psize - size of string
  220.  
  221.         PadStr returns a right-justified string.  (pstr right-justified
  222.         to psize characters).  PadStr should be used with SendString for
  223.         formatted output.  See SendString, IntStr, RealStr.
  224.  
  225.       Procedure PORTBACKGROUND(color: byte)                 ANSI
  226.         PortBackground sends the ANSI color codes to change the background
  227.         color.  Use the predefined color constants for this command.
  228.         This procedure replaces TPs CRT TextBackground.  See PortColor.
  229.  
  230.       Procedure PORTCOLOR(acolor, bcolor : byte)            ANSI
  231.         PortColor allows for color/monochrome screen control.  If
  232.         DoColor (See Unit BOIDecl) is true then acolor is the foreground
  233.         color, otherwise bcolor is the foreground color.  bcolor should
  234.         only be lightgray or white (with or without blink).
  235.         See TextPortColor, PortBackground.
  236.  
  237.       Procedure PORTCOLUMNONE                               ANSI
  238.         This procedure places the current at the left edge of the screen.
  239.         Same as GotoXY(1,WhereX) using TPs CRT.  See ResetPortXY, SetPortXY,
  240.         WhereX, WhereY.
  241.  
  242.       Function PORTKEYPRESSED
  243.         This procedure replaces the KeyPressed routine from TPs CRT.
  244.         See KeyPressed, ReadPortKey, ReadKey.
  245.  
  246.       Procedure PORTWINDOW(x1,y1,x2,y2 : byte)
  247.         Replaces TPs CRT Window(x1,y1,x2,y2).  Not as complete.  This
  248.         procedure will be upgraded greatly in the future.
  249.  
  250.       Function READKEY : char                               BIOS
  251.         Reads next character from local keyboard buffer.  This replaces
  252.         TPs CRT ReadKey.  See ReadPortKey,  CheckSecondKey (Unit IOSUPP).
  253.  
  254.       Function READPORTKEY : char
  255.         ReadPortKey returns the next waiting character from either the
  256.         local keyboard buffer or the port input buffer.  This should
  257.         be used instead of ReadKey.  This behave like TPs ReadKey except
  258.         that extended codes are not pushed into the input buffer.  They
  259.         are processed by CheckSecondKey (See Unit IOSupp).  This function
  260.         should only be called when the program is ready to wait for user
  261.         input (it will timeout after 2 minutes), or the program knows a
  262.         key is waiting (PortKeyPressed = true).
  263.         See ReadKey, PortKeyPressed.
  264.  
  265.       Function REALSTR(rval : real; rsize, rdec  : byte) : string
  266.         rval  - ennumerated value to convert to a string
  267.         rsize - size of string
  268.         rdec  - number of decimal places in string
  269.  
  270.         RealStr returns a string of a real value.  Best utilized by
  271.         SendString for formatted (left or right justified) output.
  272.         See SendString, IntStr, PadStr.
  273.  
  274.       Procedure RESETPORTXY                                 ANSI
  275.         ResetPortXY uses ANSI control codes to place the cursor at
  276.         the position stored by the most recent call to SetPortXY.
  277.  
  278.       Procedure SENDSTRING(outstr : string; docr : boolean)
  279.         outstr - string to be output
  280.         docr   - send carriage return / linefeed
  281.  
  282.         SendString is the main output function.  Senstring replaces
  283.         TPs Write and Writeln (for non-file) output procedures.
  284.         See IntStr, PadStr, RealStr.
  285.  
  286.       Procedure SETPORT                { Initialize Async Communications }
  287.         SetPort initializes the BOI communications.  This procedure should
  288.         be the one used to enable the Async routines.  See EndPort.
  289.  
  290.       Procedure SETPORTXY                                   ANSI
  291.         SetPortXY uses ANSI control codes to store the current cursor
  292.         position, so that it can be restored after some other activity
  293.         (by ResetPortXY).  You should use this procedure in your online
  294.         doors instead of using the methodology of (GotoXY, WhereX, etc.).
  295.         See ResetPortXY.
  296.  
  297.       Procedure TEXTPORTCOLOR(color : byte)   { set text attributes }
  298.         TextPortColor replaces TPs CRT TextColor procedure.  It uses
  299.         ANSI commands to set the foreground color.  A better version of
  300.         this procedure is PortColor.  See PortColor, PortBackground.
  301.  
  302.       Procedure TIMERSET(var basetime : longint)
  303.         TimerSet initializes basetime.  It sets basetime to the number
  304.         of CPU clock ticks since midnight (18.2 per second).
  305.         See GetTimer.
  306.  
  307.       Function VALID(thisfile : pathstr) : boolean;
  308.         Valid tells whether or not ThisFile is a valid Dos filename
  309.         exists or not.  Should be used in conjunction with Exist.
  310.         This is a public domain function.
  311.  
  312.       Function WHEREX : byte                                BIOS
  313.         Replaces TPs CRT WhereX.  This procedure should not be used.
  314.         You should restructure your programs to use SetPortXY and
  315.         ResetPortXY.  See WhereY.
  316.  
  317.       Function WHEREY : byte                                BIOS
  318.         Replaces TPs CRT WhereY.  This procedure should not be used.
  319.         You should restructure your programs to use SetPortXY and
  320.         ResetPortXY.  See WhereX.
  321.  
  322.  
  323.     UNIT ASYNC
  324.  
  325.       Functions
  326.         Carrier
  327.         CharReady
  328.         ReadBuffer
  329.  
  330.       Procedures
  331.         AsyncInt                  ClearInBuffer             DropCarrier
  332.         IntEnd                    IntInit                   SendChar
  333.         SetBufferSize
  334.  
  335.       Procedure ASYNCINT : Interrupt                        IRQ
  336.         This is the engine of the communications routine.  This
  337.         procedure should never be called directly.
  338.         See IntInit and IntEnd.
  339.  
  340.       Function CARRIER : boolean
  341.         Carrier returns true if carrier is detected, dolocal is true,
  342.         or carrier detect override is in effect.
  343.  
  344.       Function CHARREADY : char
  345.         CharReady returns true if the port input buffer is not empty.
  346.         See ReadBuffer.
  347.  
  348.       Procedure DROPCARRIER
  349.         DropCarrier will tell the modem to hang up the phone.  This
  350.         procedure should be used with extreme prejudice.
  351.  
  352.       Procedure INTEND
  353.         IntEnd disengages AsyncInt and restores the previous communications
  354.         interrupt.  This procedure should not be called directly.  You
  355.         should use EndPort (See Unit IOLIB).
  356.         See IntInit, AsyncInt.
  357.  
  358.       Procedure INTINIT
  359.         IntInit installs AsyncInt as the current communications interrupt
  360.         handler.  This procedure should not be called directly.  You
  361.         should use SetPort (See Unit IOLIB).
  362.         See IntEnd, AsyncInt, SetBufferSize.
  363.  
  364.       Function READBUFFER : char
  365.         ReadBuffer returns the next character in the input buffer.  This
  366.         should only be called after CharReady returns true.
  367.  
  368.       Procedure SENDCHAR(outchar : char)
  369.         SendChar sends outchar to the communications port.  This procedure
  370.         should not be called directly.  See SendString (Unit IOLIB).
  371.  
  372.       Procedure SETBUFFERSIZE(newsize : integer)
  373.         Changes size of circular input buffer.  Default is 1024 characters.
  374.         This command will also clear the buffer.
  375.  
  376.  
  377.     UNIT IOSUPP
  378.  
  379.       Procedure
  380.         CheckSecondKey
  381.  
  382.       Procedure CHECKSECONDKEY(var cskey : char)
  383.         CheckSecondKey is used to interpret extended character codes
  384.         returned by the local keyboard.  If the code is not processed,
  385.         $00 is returned.  F-9, and F-10 have default values.  You could
  386.         use this structure to implement more SysOp functions such as
  387.         ChatMode, add or subtract user time, etc...  This procedure
  388.         is used only by ReadPortKey (see UNIT IOLIB).
  389.  
  390.  
  391.     UNIT SUPPORT
  392.  
  393.       Var
  394.         playerpoints : longint;
  395.  
  396.       Function
  397.         WriteCopy
  398.  
  399.       Procedures
  400.         AbortGame
  401.         EndGame
  402.         LineWrite
  403.         QueryUser
  404.  
  405.       Procedure ABORTGAME(limit : byte)
  406.         AbortGame can be called if the user's screen size is not large
  407.         for the game to be played.
  408.  
  409.       Procedure ENDGAME(gamename,playstr,regstr,hoffile : string;
  410.           isreg,isvalid,iscash,gethigh : boolean)
  411.  
  412.         gamename - name of the current door
  413.         playstr  - gameplayer designation (Player,Trader,etc...)
  414.         regstr   - name of BBS (registered only)
  415.         hoffile  - path and name for Text Hall of Fame
  416.         isreg    - registered game indicator
  417.         isvalid  - player's score is eligible for Hall of Fame
  418.         iscash   - player's score is in dollars (false : points)
  419.         gethigh  - higher scores are better
  420.  
  421.         EndGame is my standard Hall of Fame handling routine.
  422.  
  423.       Procedure LINEWRITE(lstr : string; lcheck : boolean)
  424.         lstr   - menu selection
  425.         lcheck - highlight selection indicator
  426.  
  427.         LineWrite is one of my basic Line Menu procedures.
  428.  
  429.       Procedure QUERYUSER;
  430.         QueryUser is used to select Color or Monochrome screens.
  431.         See PortColor (Unit IOLIB).
  432.  
  433.       Function WRITECOPY(gamename,version,regnum,regstr,homestr : string;
  434.           isreg,ishome,askq : boolean) : boolean
  435.  
  436.         gamename - name of current game
  437.         version  - version of current game
  438.         regnum   - regisration number of current game
  439.         regstr   - name of BBS
  440.         homestr  - name of at home version of game
  441.         isreg    - registered game indicator
  442.         ishome   - at home version of game exists indicator
  443.         askq     - check for Instructions request indicator
  444.  
  445.         WriteCopy writes the copyrights to the screen, and optionally
  446.         questions the user to whether or not they want instructions.
  447.  
  448.  
  449.     BOI Documentation Files
  450.       BBSInfo.Doc
  451.         This is a generic information file.
  452.  
  453.       BBSNotes.Doc
  454.         This is the most complete of the documentation files, and I
  455.         recommend that it goes out with each door using a complete
  456.         and un-altered version of the BOI.
  457.  
  458.       Register.Doc
  459.         This is the registration file I include with each of my doors.
  460.  
  461.  
  462.     Future Enhancements
  463.       The windowing routines will be enhanced in the next version.
  464.       ClrPortScr will be cognizant of the actual window dimensions.
  465.       WhereX and WhereY will be fully implemented.
  466.       Procedural definition of various limits (e.g. time-out) will
  467.       be added.
  468.       More specific character input routines will be added.
  469.       All good ideas submitted will be duly considered.
  470.       A Turbo C or Turbo C++ version will be available in 1991.
  471.       A Turbo Pascal 6.0 version will also be available in early 1991.
  472.  
  473.  
  474.     Implementation Discussion
  475.       This section will be greatly enhanced in the future.  Enclosed
  476.       is a sample game that utilizes the base structure that I use
  477.       with all of my games.  The game is Hi-Lo (HILO.PAS).
  478.  
  479. END BOI Reference Manual